Update navbar design and improve search UI #1084

lhsazevedo · 2024-10-04T01:28:33Z

Tip

~~You can view this proposal live at: https://php-navbar.lhsazevedo.dev/~~
This is now live at https://php.net

Intro

Over the years, the PHP webpage received various design proposals, some didn't gain traction due to their drastic nature or departure from PHP's established branding style. However, our community has shown that we can successfully implement design improvements when they're incremental – the PHP 8 release pages, homepage hero and thanks page are great examples of this approach.

Inspired by these successful updates and the the discussions they sparked, I'd like to propose some updates to the navbar design and introduce a new search dialog to enhance a bit the user experience on php.net. These changes are inspired by modern web design principles while respecting PHP's branding and build upon previous community discussions.

By focusing on small enhancements rather than a full redesign, we can improve the site's usability and aesthetics without disrupting its familiar layout and branding.

UI Scope

It's worth noting that while the current client-side search implementation could be considered outdated, replacing it would be beyond the scope of this design improvement. Such a change would require a separate, focused effort. This proposal aims to enhance the user interface while maintaining the existing search functionality, setting the stage for potential future improvements to the search implementation itself.

Enhancements

Modernized navbar design:
- A responsive navbar with improved mobile navigation.
- Ensures a consistent experience across devices, addressing the growing mobile user base while maintaining PHP's established visual identity.
New search dialog:
- A user-friendly search modal with keyboard navigation.
- Improves accessibility with proper ARIA attributes and keyboard navigation, making php.net more inclusive.
Retained search implementation:
- Integration of the existing FuzzySearch with the new UI.
- Maintains familiar search behavior while setting the stage for future improvements to the search implementation.
Code improvements
- CSS refactoring and removal of outdated libraries (Hogan.js, typeahead.js).
- Improves maintainability, making future enhancements easier to implement.
Enhanced reliability
- Introduction of Playwright E2E tests for the new search modal.
- Ensures the changes don't introduce regressions, maintaining the site's reliability.

Impact

These changes are designed to be minimally disruptive:

Existing users will find a familiar but enhanced experience
New users will benefit from improved navigation and search UI

Preview

Please note that the preview site uses an improved search index generated by a companion change I'm proposing to the PHP documentation generator (phd). While both PRs can be merged independently, I've captured the screenshots and recordings using the new index to showcase the full potential of these improvements.

You can find the companion PR for the phd changes here: php/phd#154

Desktop preview

desktop_preview-2024-10-03_22.08.18.mp4

Mobile preview

mobile_preview-2024-10-03_22.10.47.mp4

Comparison

View GIF comparisons (image heavy)

Desktop comparison

Navbar

Search modal dialog

Mobile comparison

Navbar

Navigation

Search

Final thoughts

I believe these improvements will benefit the PHP community while respecting the site's established design principles. I look forward to your feedback and collaboration in refining this proposal.

If you find this proposal valuable or have any concerns, I'd greatly appreciate your feedback. Please consider leaving a 👍 or 👎 to help measure the community opinion.

github-actions · 2024-10-04T01:29:43Z

🚀 Preview for commit fcc9565 can be found at https://web-php-pr-1084.preview.thephp.foundation

github-actions · 2024-10-04T01:30:16Z

🚀 Regression report for commit fcc9565 is at https://web-php-regression-report-pr-1084.preview.thephp.foundation

lhsazevedo · 2024-10-04T01:30:30Z

Suggested reviewers: @morrisonlevi @dragoonis @cmb69 @kamil-tekiela @ramsey @mvriel @pronskiy @Girgias @localheinz

Edit: Will check visual tests asap

kamil-tekiela · 2024-10-04T12:06:40Z

I like it. I like the changed color, I like that the text of the buttons is more readable, I like that the PHP logo is now white, and I like that the search results list is simpler. The mobile view looks really good. There are a couple of things I don't like though.

I am not of a fan of the search opening up to cover the page. Why is it that when I click on an input box a new input box pops up? The placeholder text also doesn't match suggesting that the popup does something different than the box I actually clicked on.
If the popup stays, I would not disable the page scroll. I never liked this as it creates a jarring visual experience. At least on Chrome the page shifts to the right and the scroll bar is now in the middle box which means that if I want to scroll I need to hover my mouse over the thin box.
If the popup stays, there should be no load animation. It's an unnecessary gimmick that only delays loading of the box.
Even though the text is more readable, I still think it's not contrast enough from the background color. Especially the "Search" placeholder is visually blending in with the surroundings. Make it stand out more, either by changing the text color or giving the search box lighter border. I wouldn't mind if all text in the navbar was pure white or whitesmoke.
IMHO there is no need to make the navbar taller. The previous height was ok. On most monitors the vertical space is more expensive than horizontal, so every padding you add makes the actual content push down to a place with less priority. You made it shorter in mobile view so why make it taller in desktop view.
Not sure if related but the code formatting on /releases/8.3/en.php is borked.
The navbar is now almost the same color as the main div of /releases/8.3/en.php. Everything is purple now. I don't hate the color, but it's just too much. Something needs to change.
The logograms in mobile view have too low contrast with the background. You made them #D2D9FF but even if they were #FFFFFF they would be still too dark. I would suggest making it #F5F5F5 with opacity 1, the same as all text in the navbar.

cmb69 · 2024-10-04T12:30:09Z

Thank you! Overall, this looks like a nice improvement, but I don't like that the search now won't work if JavasScript is not available.

simonrjones · 2024-10-05T14:04:27Z

The popup search results looks very smart. A few thoughts:

Accessibility:

Contrast of primary navigation items fails WCAG accessibility (so does the current site it seems), text colour #DBE2FF or lighter would fix this
Contrast of search text fails WCAG accessibility, text colour #CBCCF1 or lighter would fix this
ALT text of PHP logo is "PHP Logo" - there's no need for the text "logo" here for accessibility reasons. Ideally it would be "PHP home" to indicate it links to the homepage.

Other:

I'd strongly recommend using progressive enhancement so the search works without JS. JS can fail for many reasons and the search should be accessible to all. The search box is a button, if this switched back to input then the form would work without JS (since would submit to the search results page)
When you do just press return it loads this full website search results page instead of the manual lookup page. It's probably more useful, but the styling is very basic on the full website search results page (I appreciate this is the same on the current site). Compare:
- https://www.php.net/manual-lookup.php?pattern=function&scope=quickref
- https://php-navbar.lhsazevedo.dev/search.php?lang=en&q=function

Girgias

The search bar not working any more with JS is a massive issue.

include/footer.inc

Adjust navbar and search modal element colors to meet WCAG AA contrast ratio. Additionally, match the search button label and input placeholder text to avoid confusion, and hides some SVG images from the accessibility tree.

CSS BEM is used in the PHP 8 Release pages and Special Thanks pages.

lhsazevedo · 2024-10-06T05:29:25Z

Thanks for the quick review and feedback! I've addressed many of your points and would like to discuss a few of them:

Progressive enhancement

@cmb69 @Girgias @simonrjones
The search was updated to work without JavaScript, using a form by default with the modal as a progressive enhancement.

Searching on mobile sized screens will still require JS. Given that it's common for mobile users to have JavaScript enabled, I think this is a reasonable trade-off. Some major language require JavaScript for searching (even on desktop): Kotlin, Rust, Swift, MDN, Dart. All Algolia-powered docs as well, and MkDocs.

Accessibility and contrast

@kamil-tekiela @simonrjones

All elements in the navbar and search modal have been updated to comply with WCAG AA contrast ratios. This includes the primary navigation items, search text, and icons in mobile view.

Layout

Page covered, no scroll

@kamil-tekiela The popup is inspired by Algolia that used in popular documentation sites (e.g. Composer, PHPStan, Laravel, Vue, React etc). It felt it a bit awkward the first time I saw it, but got used to it eventually.

The ideal UI for me would be something like Psalm docs (Material for MkDocs), but it is a bit more complicated to implement. Given the current search UI situation (5 different scrolling elements nested in a thin menu) maybe we could proceed with the Algolia-like modal as a first step and further improve it in the future. Would you consent to this approach?

Fade animation

@kamil-tekiela I believe this is a bit subjective and a matter of taste, but I can remove it if it's a common opinion. For now I halved the animation duration to 1/10th of a second, is this still a deal breaker? You can test it here (may need to disable cache).

Navbar height

@kamil-tekiela Forgot to mention but I followed @morrisonlevi's suggestion to avoid the sticky header, so now it doesn't take up any space after scrolling down. Note that the navbar is 64px tall on both desktop and mobile, which seems a common height for navbars, even sticky ones.

Other fixes

Matched the placeholder text between the search button and the modal.
Darkened the release page background a bit for better contrast with the navbar.
Hid navbar logo from the accessibility tree, as the anchor aria-label is already "PHP home".
Plus some minor adjustments, see commits.

Unrelated or out of scope

Release page formatting

@kamil-tekiela I think this is now fixed php/phd#156

Search page styling

@simonrjones Given that this is the current behavior and it relates to the page content, I think it would be out of scope for this PR. What do you think of discussing this in a separate issue?

Simplified function signatures by avoiding redundant language parameter passing, now using the one available in the outer scope. Also avoids shadowing the language variable.

Additionally, use brand blue as the selected color for search results

ddevsr · 2024-10-23T03:42:22Z

I think keep header position fixed, but after scrolling resize to small is good

Girgias · 2024-10-23T12:14:59Z

@saundefined can you have another look at this?

saundefined

I like it, thank you!

We can wait a little longer (say, until the end of the week),
and if there are no objections, merge it

lhsazevedo · 2024-10-23T17:30:01Z

Sounds good, no rush.

It would be great to have this ready for the 8.4 release though.

lhsazevedo · 2024-10-23T18:15:32Z

Fixes #502

theodorejb · 2024-10-27T22:08:48Z

Can the mobile nav sidebar be made to close when tapping outside of it? I instinctively tried to do this when testing on my phone, and it feels annoying that I instead have to tap a small X in the corner.

saundefined · 2024-10-31T08:48:21Z

@lhsazevedo can you take a look?
lhsazevedo#1

Can the mobile nav sidebar be made to close when tapping outside of it?

Should solve it

lhsazevedo · 2024-10-31T18:02:09Z

Thanks @saundefined, merged.

I noticed some common code between the offcanvas menu and the search modal.

web-php/js/search.js

Lines 315 to 321 in eb7a39d

    
               // Close when the user clicks outside of it 
        
               backdropElement.addEventListener("click", (event) => { 
        
                   if (event.target === backdropElement) { 
        
                       hide(); 
        
                   } 
        
               }); 
        
           };

In the future, we could consider refactoring this into a helper to keep things DRY. But hey, it's always good to go WET first!

Hero classes changed after php#1107. Should fix visual tests.

saundefined · 2024-11-02T14:38:07Z

So, no more comments have come in,
I guess we can merge this PR 🎉

Thanks a lot for the work done!

haszi · 2024-11-10T23:11:33Z

@lhsazevedo Thanks for this! The UI and search in general look and feel much more natural and polished.

One question I have that I couldn't find an answer to here is whether the removal of the manual lookup page is deliberate or accidental? While in it's current form it is of limited use, I did like it taking me to a function's page when I typed the full function name into the search box and hit enter.

lhsazevedo · 2024-11-12T23:53:01Z

@haszi Great to hear that :)

The Google Search was a conscious decision (now the lookup it is only used when JavaScript is not available), but I also thought that this was the previous behavior. I just checked the previous implementation, and indeed, hitting enter would trigger the lookup.

While I think the Google search would benefit most of the users, I can see the value of the lookup use as well. Considering only those two implementations, I see two options:

Restore the old behavior, were Enter triggers the lookup and the Google search option is the last entry in the result list.
Keep it as is, with the lookup alternative being to navigate to the desired result with ↓, then Enter.

Both sound reasonable to me, so I don't have a strong preference. I can implement the first option if desired, plus some minor quality-of-life adjustments, by next week.

haszi · 2024-11-24T20:25:35Z

While I liked the search bar immediately taking me to a function's documentation, I don't have any strong preferences on this. And since I'm not active in web-php, neither do I think my opinion should carry too much weight. :-) That I leave up to those who do take care of the repo, like @saundefined . :-)

lhsazevedo added 5 commits October 3, 2024 20:05

Update navbar design

03491d5

Add new search modal dialog

89c598e

Add search modal e2e tests

8650771

Remove Hogan.js and typeahead.js

d0da0c8

Update playwright snapshots

831f80c

lhsazevedo requested review from saundefined and sy-records as code owners October 4, 2024 01:28

Fix e2e and visual tests

b17b606

lhsazevedo mentioned this pull request Oct 4, 2024

Improve search index generation for PHP.net php/phd#154

Merged

lhsazevedo added 2 commits October 4, 2024 18:36

Avoid page shift when opening the search modal

0048ef1

Match search label and input placeholder text

b83f783

Girgias requested changes Oct 5, 2024

View reviewed changes

include/footer.inc Outdated Show resolved Hide resolved

include/footer.inc Outdated Show resolved Hide resolved

include/footer.inc Outdated Show resolved Hide resolved

include/footer.inc Outdated Show resolved Hide resolved

lhsazevedo added 10 commits October 5, 2024 23:32

Increase contrast for accessibility

23003ff

Adjust navbar and search modal element colors to meet WCAG AA contrast ratio. Additionally, match the search button label and input placeholder text to avoid confusion, and hides some SVG images from the accessibility tree.

Halve the transition duration of the search modal

cd0754b

Reduce search scrollbar width

07da74b

Darken release background to better fit the navbar

ec7e9b9

Fallback search when Javascript is disabled

7146752

Remove logo alt text

535b25d

Fix modal input type and aria-label

b8bb98c

Use <kbd> tag

75a3e38

Use correct CSS methodology

9fe9ed1

CSS BEM is used in the PHP 8 Release pages and Special Thanks pages.

Avoid search flash on mobile

4c062ec

Fix e2e and visual tests

21b220e

lhsazevedo added 6 commits October 21, 2024 20:08

Fix leftover vars

6a4dcd1

Use current language in legacy global search

2d89914

Add missing docblocks and improve existing ones

e35fe6e

Use language parameter from outer scope

1fa0853

Simplified function signatures by avoiding redundant language parameter passing, now using the one available in the outer scope. Also avoids shadowing the language variable.

Format search.js

d2d68a0

Tone down result hover background color

39bc218

Additionally, use brand blue as the selected color for search results

lhsazevedo force-pushed the navbar-2024 branch from 4522fe1 to 39bc218 Compare October 22, 2024 23:51

lhsazevedo added 2 commits October 22, 2024 23:49

Update visual tests snapshots

0d5a896

Add search modal visual test

f97426e

Fix visual tests snapshots

eb7a39d

lhsazevedo force-pushed the navbar-2024 branch from 77ba1cf to eb7a39d Compare October 23, 2024 04:52

saundefined approved these changes Oct 23, 2024

View reviewed changes

lhsazevedo mentioned this pull request Oct 23, 2024

Convert homepage hero section styles to use BEM methodology #1102

Closed

saundefined added the hacktoberfest-accepted label Oct 31, 2024

Close offcanvas menu by outside click

614a1ad

Sync class name with master

d54e103

Hero classes changed after php#1107. Should fix visual tests.

saundefined merged commit b62f99f into php:master Nov 2, 2024
5 checks passed

lhsazevedo deleted the navbar-2024 branch November 11, 2024 05:37

saundefined mentioned this pull request Nov 25, 2024

Search bar breaks layout and hides text on viewports 768-858px #502

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update navbar design and improve search UI #1084

Update navbar design and improve search UI #1084

lhsazevedo commented Oct 4, 2024 •

edited

Loading

github-actions bot commented Oct 4, 2024 •

edited

Loading

github-actions bot commented Oct 4, 2024 •

edited

Loading

lhsazevedo commented Oct 4, 2024 •

edited

Loading

kamil-tekiela commented Oct 4, 2024 •

edited

Loading

cmb69 commented Oct 4, 2024

simonrjones commented Oct 5, 2024

Girgias left a comment

lhsazevedo commented Oct 6, 2024 •

edited

Loading

ddevsr commented Oct 23, 2024

Girgias commented Oct 23, 2024

saundefined left a comment

lhsazevedo commented Oct 23, 2024 •

edited

Loading

lhsazevedo commented Oct 23, 2024

theodorejb commented Oct 27, 2024

saundefined commented Oct 31, 2024

lhsazevedo commented Oct 31, 2024

saundefined commented Nov 2, 2024

haszi commented Nov 10, 2024

lhsazevedo commented Nov 12, 2024

haszi commented Nov 24, 2024

Update navbar design and improve search UI #1084

Update navbar design and improve search UI #1084

Conversation

lhsazevedo commented Oct 4, 2024 • edited Loading

Intro

UI Scope

Enhancements

Impact

Preview

Desktop preview

Mobile preview

Comparison

Desktop comparison

Navbar

Search modal dialog

Mobile comparison

Navbar

Navigation

Search

Final thoughts

github-actions bot commented Oct 4, 2024 • edited Loading

github-actions bot commented Oct 4, 2024 • edited Loading

lhsazevedo commented Oct 4, 2024 • edited Loading

kamil-tekiela commented Oct 4, 2024 • edited Loading

cmb69 commented Oct 4, 2024

simonrjones commented Oct 5, 2024

Girgias left a comment

Choose a reason for hiding this comment

lhsazevedo commented Oct 6, 2024 • edited Loading

Progressive enhancement

Accessibility and contrast

Layout

Page covered, no scroll

Fade animation

Navbar height

Other fixes

Unrelated or out of scope

Release page formatting

Search page styling

ddevsr commented Oct 23, 2024

Girgias commented Oct 23, 2024

saundefined left a comment

Choose a reason for hiding this comment

lhsazevedo commented Oct 23, 2024 • edited Loading

lhsazevedo commented Oct 23, 2024

theodorejb commented Oct 27, 2024

saundefined commented Oct 31, 2024

lhsazevedo commented Oct 31, 2024

saundefined commented Nov 2, 2024

haszi commented Nov 10, 2024

lhsazevedo commented Nov 12, 2024

haszi commented Nov 24, 2024

lhsazevedo commented Oct 4, 2024 •

edited

Loading

github-actions bot commented Oct 4, 2024 •

edited

Loading

github-actions bot commented Oct 4, 2024 •

edited

Loading

lhsazevedo commented Oct 4, 2024 •

edited

Loading

kamil-tekiela commented Oct 4, 2024 •

edited

Loading

lhsazevedo commented Oct 6, 2024 •

edited

Loading

lhsazevedo commented Oct 23, 2024 •

edited

Loading